home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / dev / gcc / ixemsdk.lha / man / cat3 / vis.0 < prev    next >
Text File  |  1996-09-02  |  6KB  |  121 lines
  1.  
  2. VIS(3)                     UNIX Programmer's Manual                     VIS(3)
  3.  
  4. NNAAMMEE
  5.      vviiss - visually encode characters
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ##iinncclluuddee <<vviiss..hh>>
  9.  
  10.      _c_h_a_r _*
  11.      vviiss(_c_h_a_r _*_d_s_t, _c_h_a_r _c, _i_n_t _f_l_a_g, _c_h_a_r _n_e_x_t_c)
  12.  
  13.      _i_n_t
  14.      ssttrrvviiss(_c_h_a_r _*_d_s_t, _c_h_a_r _*_s_r_c, _i_n_t _f_l_a_g)
  15.  
  16.      _i_n_t
  17.      ssttrrvviissxx(_c_h_a_r _*_d_s_t, _c_h_a_r _*_s_r_c, _i_n_t _l_e_n, _i_n_t _f_l_a_g)
  18.  
  19. DDEESSCCRRIIPPTTIIOONN
  20.      The vviiss() function copies into _d_s_t a string which represents the charac-
  21.      ter _c. If _c needs no encoding, it is copied in unaltered.  The string is
  22.      null terminated, and a pointer to the end of the string is returned.  The
  23.      maximum length of any encoding is four characters (not including the
  24.      trailing NUL); thus, when encoding a set of characters into a buffer, the
  25.      size of the buffer should be four times the number of characters encoded,
  26.      plus one for the trailing NUL. The flag parameter is used for altering
  27.      the default range of characters considered for encoding and for altering
  28.      the visual representation.  The additional character, _n_e_x_t_c, is only used
  29.      when selecting the VIS_CSTYLE encoding format (explained below).
  30.  
  31.      The ssttrrvviiss() and ssttrrvviissxx() functions copy into _d_s_t a visual representa-
  32.      tion of the string _s_r_c. The ssttrrvviiss() function encodes characters from _s_r_c
  33.      up to the first NUL. The ssttrrvviissxx() function encodes exactly _l_e_n charac-
  34.      ters from _s_r_c (this is useful for encoding a block of data that may con-
  35.      tain NUL's). Both forms NUL terminate _d_s_t. The size of _d_s_t must be four
  36.      times the number of characters encoded from _s_r_c (plus one for the NUL).
  37.      Both forms return the number of characters in dst (not including the
  38.      trailing NUL).
  39.  
  40.      The encoding is a unique, invertible representation comprised entirely of
  41.      graphic characters; it can be decoded back into the original form using
  42.      the unvis(3) or strunvis(3) functions.
  43.  
  44.      There are two parameters that can be controlled: the range of characters
  45.      that are encoded, and the type of representation used.  By default, all
  46.      non-graphic characters.  except space, tab, and newline are encoded.
  47.      (See isgraph(3).)  The following flags alter this:
  48.  
  49.      VIS_SP      Also encode space.
  50.  
  51.      VIS_TAB
  52.                  Also encode tab.
  53.  
  54.      VIS_NL      Also encode newline.
  55.  
  56.      VIS_WHITE   Synonym for VIS_SP | VIS_TAB | VIS_NL.
  57.  
  58.      VIS_SAFE    Only encode "unsafe" characters.  Unsafe means control char-
  59.                  acters which may cause common terminals to perform unexpected
  60.                  functions.  Currently this form allows space, tab, newline,
  61.                  backspace, bell, and return - in addition to all graphic
  62.                  characters - unencoded.
  63.  
  64.      There are three forms of encoding.  All forms use the backslash character
  65.      `\' to introduce a special sequence; two backslashes are used to repre-
  66.  
  67.      sent a real backslash.  These are the visual formats:
  68.  
  69.      (default)   Use an `M' to represent meta characters (characters with the
  70.                  8th bit set), and use caret `^' to represent control charac-
  71.                  ters see (iscntrl(3)).  The following formats are used:
  72.  
  73.                  \^C    Represents the control character `C'. Spans characters
  74.                         `\000' through `\037', and `\177' (as `\^?').
  75.  
  76.                  \M-C   Represents character `C' with the 8th bit set.  Spans
  77.                         characters `\241' through `\376'.
  78.  
  79.                  \M^C   Represents control character `C' with the 8th bit set.
  80.                         Spans characters `\200' through `\237', and `\377' (as
  81.                         `\M^?').
  82.  
  83.                  \040   Represents ASCII space.
  84.  
  85.                  \240   Represents Meta-space.
  86.  
  87.      VIS_CSTYLE  Use C-style backslash sequences to represent standard non-
  88.                  printable characters.  The following sequences are used to
  89.                  represent the indicated characters:
  90.  
  91.                        \a - BEL (007)
  92.                        \b - BS (010)
  93.                        \f - NP (014)
  94.                        \n - NL (012)
  95.                        \r - CR (015)
  96.                        \t - HT (011)
  97.                        \v - VT (013)
  98.                        \0 - NUL (000)
  99.  
  100.                  When using this format, the nextc parameter is looked at to
  101.                  determine if a NUL character can be encoded as `\0' instead
  102.                  of `\000'. If _n_e_x_t_c is an octal digit, the latter representa-
  103.                  tion is used to avoid ambiguity.
  104.  
  105.      VIS_OCTAL   Use a three digit octal sequence.  The form is `\ddd' where _d
  106.                  represents an octal digit.
  107.  
  108.      There is one additional flag, VIS_NOSLASH, which inhibits the doubling of
  109.      backslashes and the backslash before the default format (that is, control
  110.      characters are represented by `^C' and meta characters as `M-C'). With
  111.      this flag set, the encoding is ambiguous and non-invertible.
  112.  
  113. SSEEEE AALLSSOO
  114.      vis(1),  unvis(1),  unvis(3)
  115.  
  116. HHIISSTTOORRYY
  117.      These functions first appeared in 4.4BSD.
  118.  
  119.  
  120. BSD Experimental                 June 9, 1993                                2
  121.